[% setvar title Multiline Comments for Perl. %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Multiline Comments for Perl.</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Michael J. Mathews &lt;<a href='mailto:mmathews@oxygen.com'>mmathews@oxygen.com</a>&gt;
  Date: 14 Aug 2000
  Mailing List: <a href='mailto:perl6-language-mlc@perl.org'>perl6-language-mlc@perl.org</a>
  Number: 5
  Version: 3
  Status: Frozen</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>Unlike many programming languages Perl does not currently implement true
multiline comments. This, and the workarounds that are in common use can be
problematic. This could be solved by adding a new syntax to allow for
comments to span more than one line, like the variation on
here-documentation cited below.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>Comments are a standard and important way for programmers to make their code
more understandable and therefore more maintainable. It is also a vital tool
for isolating bugs in programs and for temporarily &quot;turning off&quot; sections of
code as part of testing. Programmers who wish to include comments across
many lines are currently required to start each line with an unquoted hash
symbol (&quot;#&quot;), which removes all text until the next newline from the Perl
interpreter.</p>
<a name='THE PROBLEM'></a><h2>THE PROBLEM</h2>
<p>For very small programs the single-line comment is sufficient. More and more
however programmers are choosing Perl as the best tool for bigger projects,
possibly involving thousands of lines of code. Other popular languages (like
Java and C++) that were designed from the outset as being useful for large
projects implement both singleline and multiline comments. Some languages
like Java also have a third type of &quot;comment&quot; which can be used for inline
documentation (the distinction being that these items are meant to be viewed
separate from the actual code).</p>
<p>The languages mentioned above have a distinct advantage over Perl in this
regard. They encourage easy and consistent multiline comments. The
alternatives available to Perl programmers however are neither easy (comment
each and every line of code individually, possibly with the aid of a macro
they've written, or that might have been built-in to their particular
text-editor), nor consistent (use some other language feature to simulate
multiline comments, like POD).</p>
<a name='WHAT'S WRONG WITH POD?'></a><h2>WHAT'S WRONG WITH POD?</h2>
<p>The fact that so many people on the List suggested using POD (implying this
is a common work-around to the lack of true multiline comments) points out
how many people would like the functionality. However POD has at least three
problems:</p>
<li><a name='IT'S NOT INTUITIVE'></a>IT'S NOT INTUITIVE</li>
<p>Novice Perl programmers who are more-likely-than-not to be familiar with C++
comments can learn the &quot;#...\n&quot; comment syntax easily enough but POD has a
completely different syntax, unrelated to &quot;#&quot;, and is often not listed in
reference books as being related to comments at all (PP3 a notable
exception).</p>
<li><a name='IT'S NOT DOCUMENTATION'></a>IT'S NOT DOCUMENTATION</li>
<p>POD, of course stands for &quot;Plain Old Documentation&quot; but most of the time
comments are not intended to be included in documentation (separate from the
code). This is particularly true when using comments as a debugging tool.
This adds to the Not Intuitive, and Not Consistent problems mentioned here.</p>
<li><a name='IT DOESN'T ENCOURAGE CONSISTENCY'></a>IT DOESN'T ENCOURAGE CONSISTENCY</li>
<p>Even if someone did know about POD's ability to act like comments, there is
no standard syntax required for POD that is specifically meant to be a
comment. This leaves it up to the programmer to try any of these sorts of
methods:</p>
<pre> =begin ARBITRARYTEXT
 ...
 =end ARBITRARYTEXT
 =cut

 =ARBIRTARYTEXT
 ...
 =cut

 =for TRANSLATOR
 ...
 =cut</pre>
<p>Since there is no standard, finding these types of comments in other
people's code (or even your own) is made more difficult. Further there is
currently no guarantee to insure that the POD you are using for comments
will some day be used as part of some legitimate POD.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>Perl currently allows for single-line comments using the pound-symbol &quot;#&quot;.
Any implementation of a Perl multilline comment should feel similar to this.
However (ideally) the multiline syntax would be unique enough so that it
would not conflict with older scripts using the singleline &quot;#&quot; syntax.</p>
<a name='Nesting'></a><h2>Nesting</h2>
<p>Since multiline comments will have a beginning and an ending it will be
possible to nest and overlap commented sections of Perl. Overlapping should
not be allowed however for several reasons: it will make the parsing job
considerably harder, it will make the syntax more confusing. Nesting on the
other hand should be simple to implement if we enforce what Glenn Linderman
calls &quot;block opacity&quot; -- his term for the fact that anything within a
comment block should be invisible to the parser, up to the end of the
comment block. This implies and requires that multiline comment blocks have
different and fairly unique block delimiters.</p>
<a name='THE LIST REACTS'></a><h1>THE LIST REACTS</h1>
<a name='General reaction'></a><h2>General reaction</h2>
<p>The comments from the language-list can be classed into three general
reactions: 1) those that thought multiline comments were not needed at all,
2) those that thought they should be implemented as a function, and 3) those
that felt we needed a new syntax entirely. No one, however commented that
they liked the original proposed implementation of using the <code>(#...#)</code>
syntax.</p>
<a name='Is it needed?'></a><h2>Is it needed?</h2>
<p>Many in the community suggested that there are already adequate features in
the language to fulfill the requirements that multiline comments are meant
to address. The most frequent example cited was POD while others suggested
that many single-line comments should be used.</p>
<a name='The response...'></a><h2>The response...</h2>
<p>It was stated by others that using POD as a commenting mechanism had
problems, including: 1) it doesn't allow the programmer to distinguish their
comments from actual inline documentation; 2) it allows (requires?)
non-standard usage -- since programmers can label the comment/POD anything
they wish; 3) it cannot be nested since <code>=cut</code> closes <i>all</i> previously
opened POD sections, and would therefore require the programmer to remove
any <code>=cut</code> tags within a section that she wished to be comment.</p>
<a name='A comment function:'></a><h2>A comment function:</h2>
<p>Many who responded stated that if it were to be added that it would best be
added to an existing Perl feature, or made to work just like one. The most
frequently suggested of these was a version of qc() which would return
empty/undefined but not cause a warning under <code>warn</code>.</p>
<a name='The response...'></a><h2>The response...</h2>
<p>It was pointed out that using a function as a commenting mechanism suffers
two problems: 1) it means that the argument delimiter cannot appear in the
commented string (tricky when commenting large sections of possibly buggy
code); and 2) it doesn't &quot;stand out&quot; from the rest of the code as a comment
should.</p>
<a name='Keep it perlish'></a><h2>Keep it perlish</h2>
<p>Other suggestions were to utilize a Perl (or perlish) syntax to accomplish
the goal. One promising suggestion was a variation on the here-documentation
syntax which would return empty/undefined and not cause a warning.</p>
<pre> #&lt;&lt;TOKEN;
 comments
 TOKEN</pre>
<a name='NOTES'></a><h1>NOTES</h1>
<p>This issue was originally discusssed on <a href='mailto:perl6-language@perl.org.'>perl6-language@perl.org.</a>
After creating a sublist for discussing multi-line comments
(<a href='mailto:perl5-language-mlc@perl.org'>perl5-language-mlc@perl.org</a>), there was no clear consensus on
this issue after one week's discussion.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>Randal L. Schwartz &amp; Tom Christiansen
<a href='http://www.oreilly.com/catalog/lperl2/chapter/ch01.html' target='_blank'>www.oreilly.com</a>
&quot;Perl comments are like (modern) shell comments. Anything from an unquoted
pound sign (#) to the end of the line is a comment. There are no C-like
multiline comments.&quot;</p>
<p>Larry Wall
PERLPOD.pod (standard distribution)</p>
<p>Larry Wall, et al.
Programming Perl (3rd. edition). pages 630 - 631, 634.</p>
<p>Tom Christiansen
PERLSYN.pod (standard distribution)</p>
<p>Dr Nikolai Bezroukov
<a href='http://www.softpanorama.org/Scripting/Perl/Ch02_overview/lex_and_syntax.shtml' target='_blank'>www.softpanorama.org</a>#Comments
&quot;Perl has rather inflexible and limited comments. The desire to preserve
compatibility with shell languages dictated the use of #, but here Perl
robbed itself of [an] important symbol (that can be used, for example for
casting scalars into numeric). This differences creates problems for heavy
users of C-like languages and one can write a preprocessor that permits
usage of C and C++ style comments. In any case if you are C programmer you
need to check you scripts for wrong comments...&quot;</p>
</div>
